fix(agent-core/mcp): sanitize MCP JSON Schemas for Moonshot MFJS validator by creatiVision · Pull Request #830 · MoonshotAI/kimi-code

creatiVision · 2026-06-16T21:51:40Z

Related Issue

Resolves #792, #1610, #2661.
Related / config fixes: #2421, #302.
Continues / supersedes the earlier drafts in #1605 and #2216.

Problem

MCP servers often advertise standard JSON Schema tool parameters. Moonshot’s stricter MFJS validator (and Kimi’s discovery path) reject or crash on several common shapes:

Circular / recursive $ref → stack overflow during processing
Missing type on properties (enum/structure-only schemas) → type is not defined
Tuple-style items arrays → items must be an object
Mixed-type enums (e.g. [1, "auto"]) must not be collapsed to a single forced type
type alongside anyOf/oneOf → not a valid moonshot flavored json schema

What changed

Add sanitizeMcpSchema and run it after MCP tool discovery in McpConnectionManager (packages/agent-core/src/mcp/).
Local $ref inlining with RFC 6901 pointer unescaping (~1/~0) and circular-safe placeholders.
Missing-type filling from enum/const/structure.
Tuple items → prefixItems + minItems/maxItems (preserves positional validation).
Mixed enums → typed anyOf branches (preserves all members).
Config compatibility: disabled → enabled, max_tokens / max_output_tokens → maxOutputSize (Bug: [tools].disabled in config.toml does not filter MCP tools from the request #2421).
Unit tests for sanitizer + config aliases (packages/agent-core/test/mcp/schema-sanitize.test.ts, all 75 tests green).
Changeset included.

Checklist

CONTRIBUTING read
Problem explained / related issues linked (MCP tool schema validation fails with HTTP 400 ("moonshot flavored json schema") due to missing schema sanitization in new CLI #792, 400 error: "tools.function.parameters is not a valid moonshot flavored json schema" when using custom API endpoint with MCP tools #1610, bug: 400 "not a valid moonshot flavored json schema" when an MCP tool schema declares type next to anyOf #2661, Bug: [tools].disabled in config.toml does not filter MCP tools from the request #2421)
Tests added (schema-sanitize, config-loader, configs)
Changeset included
Rebased cleanly on latest main

changeset-bot · 2026-06-16T21:51:45Z

🦋 Changeset detected

Latest commit: c285628

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@moonshot-ai/agent-core-v2	Patch
@moonshot-ai/kimi-code	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f20830c5c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Cherry-pick PR MoonshotAI#830's changes onto current upstream main, resolving the merge conflict in transformModelData (toml.ts) introduced by main's overrides-transform refactor: - schema.ts: add incompatible 'disabled' -> 'enabled' preprocess mapping - toml.ts: keep the overrides transform and add the max_tokens / max_output_tokens -> maxOutputSize alias fallback - Add sanitizeMcpSchema (MFJS emitter) + cycle detector + root-pointer comment addressing Codex review feedback on PR MoonshotAI#830 - Integrate the sanitizer into connectAndDiscoverTools - Update schema-sanitize export in index.ts - Add tests + changeset

creatiVision · 2026-07-27T09:21:26Z

Addressed the three Codex review notes on schema-sanitize.ts (commit on this branch):

Tuple items — no longer collapsed to items: { anyOf: [...] }. Draft-07 tuple arrays are rewritten to prefixItems + minItems/maxItems so positional validation is preserved (and Moonshot still gets a non-array items shape avoided).
JSON Pointer array segments — #/$defs/X/anyOf/0 style paths now index into arrays per RFC 6901 instead of throwing and failing the whole MCP server.
$ref siblings — sibling keywords are run through traverse before merge so nested local $refs are inlined before $defs/definitions are stripped.

Tests: schema-sanitize.test.ts (28) green locally.

creatiVision · 2026-08-18T07:08:40Z

🔄 Status Update & Necessity Note

Rebased cleanly onto latest main (passing all lint, typecheck, and unit test suites: 75 tests green).

Why this PR is still necessary:

Ecosystem Compatibility: Standard MCP servers across the ecosystem (e.g., community PostgreSQL, Filesystem, Xcode, Git, and custom Python/TypeScript MCP servers) output standard Draft-07 / 2020-12 JSON Schema definitions for tool input parameters.
MFJS Validation Rejections: Moonshot's backend enforces MFJS (Moonshot-Flavored JSON Schema), which strictly rejects:
- Nested or circular $ref definitions (causing recursion / stack overflow or schema rejection).
- Properties missing an explicit type field (e.g. pure enum or object structures).
- Positional tuple arrays with array-based items (instead of prefixItems).
- Coexisting type with anyOf / oneOf constructs (bug: 400 "not a valid moonshot flavored json schema" when an MCP tool schema declares type next to anyOf #2661).
- Mixed-type enums (MCP tool schema validation fails with HTTP 400 ("moonshot flavored json schema") due to missing schema sanitization in new CLI #792, 400 error: "tools.function.parameters is not a valid moonshot flavored json schema" when using custom API endpoint with MCP tools #1610).
User Impact: Without client-side sanitization in McpConnectionManager, attempting to connect and use these standard MCP servers leads to immediate HTTP 400 ("tools.function.parameters is not a valid moonshot flavored json schema") errors during turn execution, breaking tool calls completely.

This PR provides lightweight, deterministic schema sanitization during MCP tool discovery so all standard MCP tools work out-of-the-box.

…ap disabled config

creatiVision · 2026-09-07T07:12:46Z

Rebased and updated onto latest main. With upstream's removal of the legacy packages/agent-core engine (#3542), all MCP schema sanitization and config compatibility logic have been cleanly rebased into packages/agent-core-v2 (src/mcpCore):

packages/agent-core-v2/src/mcpCore/schema-sanitize.ts: Deterministically sanitizes standard MCP tool JSON Schemas for Moonshot's MFJS validator (inlines local $ref with circular reference detection, infers missing type from enums/consts/structure, converts positional tuple items arrays into an anyOf schema object, and splits mixed enums).
packages/agent-core-v2/src/mcpCore/connection-manager.ts: Integrates sanitizeMcpSchema directly into tool discovery.
packages/agent-core-v2/src/mcpCore/config-schema.ts: Normalizes standard disabled configuration property to enabled.
Comprehensive unit tests in schema-sanitize.test.ts (14 tests green, strictly adhering to the comment-free requirement for agent-core-v2).
Changeset included.

All merge conflicts are resolved and the PR is clean, mergeable, and ready for review.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c285628f9e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-09-08T17:44:12Z

        name: mcpTool.name,
        description: mcpTool.description,
-        parameters: assertMcpInputSchema(mcpTool.name, mcpTool.inputSchema),
+        parameters: sanitizeMcpSchema(assertMcpInputSchema(mcpTool.name, mcpTool.inputSchema)),


Keep Kimi-only normalization out of MCP discovery

When using Anthropic, OpenAI, or Google with an MCP tool, this stores the Kimi-specific rewrite in the shared Tool.parameters; those request formatters and the tool-argument validator subsequently consume the rewritten schema unchanged. Valid schemas such as a typeless arbitrary-value property are therefore narrowed to string, and tuple schemas are altered even though those providers can accept the original schema, causing models to generate or local validation to reject otherwise valid arguments. Preserve the MCP schema here and apply this compatibility normalization only in the Kimi request path.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-09-08T17:44:12Z

+    } else if (items.length === 1) {
+      record['items'] = items[0] as Json;
+    } else {
+      record['items'] = { anyOf: items };


Preserve tuple positions when replacing array-form items

For a draft-07 tuple such as items: [{type: 'number'}, {type: 'string'}], replacing items with a single anyOf schema allows either type at every position instead of preserving each positional constraint. It also makes an accompanying additionalItems: false ineffective, so extra elements become valid. This can let the model and local argument validator accept calls the MCP server rejects; convert to an equivalent positional representation rather than collapsing the branches.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-09-08T17:44:12Z

+    const record = node as JsonRecord;
+    if (typeof record['$ref'] === 'string') {
+      const ref = record['$ref'];
+      if (ref.startsWith('#')) {


Resolve or preserve plain-name fragment references

When a valid modern JSON Schema uses $anchor: 'node' and $ref: '#node', this condition treats the plain-name fragment as a JSON Pointer; resolvePointer then looks for a top-level node property and throws if it is absent. Because sanitization runs during discovery, one such tool marks the entire MCP connection failed, including for non-Kimi providers. Restrict pointer resolution to # and #/..., or implement $anchor lookup and preserve unsupported fragments.

Useful? React with 👍 / 👎.

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread packages/agent-core/src/mcp/schema-sanitize.ts Outdated

creatiVision force-pushed the fix/mcp-schema-limits branch from 6fc34e7 to c359747 Compare July 5, 2026 20:07

creatiVision force-pushed the fix/mcp-schema-limits branch from ca113cd to 03873ad Compare July 13, 2026 10:14

creatiVision mentioned this pull request Jul 13, 2026

fix(agent-core/mcp): support tuple array items in JSON Schema sanitizer #1605

Closed

5 tasks

creatiVision mentioned this pull request Jul 27, 2026

fix(agent-core/mcp): sanitize recursive MCP JSON Schemas for Moonshot validator compatibility #2216

Closed

5 tasks

creatiVision force-pushed the fix/mcp-schema-limits branch from dd82ba7 to a0fc9fe Compare July 27, 2026 08:36

creatiVision changed the title ~~fix(agent-core): prevent stack overflow on circular schema refs & add compatibility mappings~~ fix(agent-core/mcp): sanitize MCP JSON Schemas for Moonshot MFJS validator Jul 27, 2026

creatiVision mentioned this pull request Jul 27, 2026

fix(agent-core/mcp): sanitize MCP JSON Schemas for Moonshot MFJS vali… #2242

Closed

5 tasks

creatiVision force-pushed the fix/mcp-schema-limits branch 3 times, most recently from 6d335a7 to 797107d Compare August 15, 2026 13:12

creatiVision force-pushed the fix/mcp-schema-limits branch from 797107d to a2da2c3 Compare August 18, 2026 07:05

creatiVision mentioned this pull request Aug 18, 2026

feat(tui): add hierarchical skill group selector with tab navigation #2995

Closed

5 tasks

creatiVision force-pushed the fix/mcp-schema-limits branch 2 times, most recently from fb498a3 to 10dc44d Compare August 20, 2026 20:11

creatiVision mentioned this pull request Aug 24, 2026

MCP tool schema validation fails with HTTP 400 ("moonshot flavored json schema") due to missing schema sanitization in new CLI #792

Open

creatiVision force-pushed the fix/mcp-schema-limits branch 2 times, most recently from 51ab3ef to 04dba24 Compare August 28, 2026 07:25

creatiVision mentioned this pull request Sep 1, 2026

400 error: "tools.function.parameters is not a valid moonshot flavored json schema" when using custom API endpoint with MCP tools #1610

Open

fix(mcp): sanitize MCP JSON schemas for Moonshot MFJS validator and m…

b759414

…ap disabled config

creatiVision force-pushed the fix/mcp-schema-limits branch from b33fe94 to b759414 Compare September 7, 2026 07:12

Merge branch 'main' into fix/mcp-schema-limits

c285628

chatgpt-codex-connector Bot reviewed Sep 8, 2026

View reviewed changes

Navigation Menu

Uh oh!

fix(agent-core/mcp): sanitize MCP JSON Schemas for Moonshot MFJS validator - #830

fix(agent-core/mcp): sanitize MCP JSON Schemas for Moonshot MFJS validator#830
creatiVision wants to merge 2 commits into
MoonshotAI:mainfrom
creatiVision:fix/mcp-schema-limits

creatiVision commented Jun 16, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 16, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

creatiVision commented Jul 27, 2026

Uh oh!

creatiVision commented Aug 18, 2026

Uh oh!

creatiVision commented Sep 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Sep 8, 2026

Uh oh!

chatgpt-codex-connector Bot Sep 8, 2026

Uh oh!

chatgpt-codex-connector Bot Sep 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

creatiVision commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issue

Problem

What changed

Checklist

Uh oh!

changeset-bot Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

creatiVision commented Jul 27, 2026

Uh oh!

creatiVision commented Aug 18, 2026

🔄 Status Update & Necessity Note

Why this PR is still necessary:

Uh oh!

creatiVision commented Sep 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Sep 8, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Sep 8, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Sep 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

creatiVision commented Jun 16, 2026 •

edited

Loading

changeset-bot Bot commented Jun 16, 2026 •

edited

Loading